Skip to content

Conversation

@ammar-agent
Copy link
Collaborator

Summary

Improves documentation visual design and reorganizes workspace documentation for better clarity.

Visual Design Improvements

Blockquotes

  • Enhanced styling with support for GitHub-style alerts (Note, Tip, Important, Warning, Caution)
  • Color-coded left borders for each alert type
  • Consistent border-radius throughout

Border-Radius

  • Restored consistent border-radius across all UI elements (8px/6px/4px/3px)
  • Fixed table border-radius rendering (switched from border-collapse: collapse to separate)
  • Applied to: blockquotes, code blocks, inline code, tables, details, images, mermaid diagrams

Server Configuration

  • mdbook server now binds to 0.0.0.0 for remote access

Documentation Organization

Workspace Pages

  • Created dedicated docs/local.md for local workspace details
  • Simplified docs/workspaces.md to high-level overview
  • Moved reviewing sections to main Workspaces page (applies to both local and SSH)

New structure:

Workspaces (overview + reviewing workflows)
├── Local (git worktrees specifics)
├── SSH (remote workspaces)
├── Forking
└── Init Hooks

Development Setup

  • Added mdbook tools to nix devShell for easier local development

Generated with cmux

Add mdbook, mdbook-mermaid, and mdbook-linkcheck to the nix development
shell for building documentation locally.

These tools are required by the docs build scripts (scripts/docs.sh and
scripts/docs_build.sh).
Change `mdbook serve` to bind to 0.0.0.0 instead of localhost,
allowing remote access to the docs server. This is useful for
development environments like remote servers or containers.
Improve blockquote design:
- Increase padding and add border-radius for better visual appeal
- Add subtle box-shadow for depth
- Support GitHub-style alerts (Note, Tip, Important, Warning, Caution)
- Color-coded left borders for each alert type:
  - Note: blue
  - Tip: green
  - Important: purple
  - Warning: orange
  - Caution: red
- Better paragraph spacing within blockquotes

Usage:
> **Note**: This is a note
> **Warning**: This is a warning
> **Tip**: This is a tip
Set all border-radius values to 0 for a sharper, more consistent
visual style across all elements (blockquotes, code blocks, tables,
details, images, inputs, etc.).
Remove full border and box-shadow from blockquotes, keeping only the
left border accent. This eliminates the diagonal corner artifacts that
occurred when mixing thin borders with thick left borders at 0 radius.

Changes:
- Remove 1px full border (only keep 3px left border)
- Remove box-shadow
- Increase background opacity slightly for better contrast
- Cleaner look that works well with sharp corners
Bring back border-radius to fix diagonal border artifacts while
maintaining a cohesive look throughout the UI.

Changes:
- Set consistent border-radius values (lg: 8px, md: 6px, sm: 4px, xs: 3px)
- Apply to blockquotes (fixes diagonal corner issue)
- Apply to inline code (xs: 3px)
- Apply to code blocks (md: 6px)
- Already applied to: tables, details, mermaid, images, kbd, search

All UI elements now have matching rounded corners for a polished,
consistent appearance.
Tables weren't showing rounded corners because `border-collapse: collapse`
prevents border-radius from working.

Changes:
- Use `border-collapse: separate` with `border-spacing: 0`
- Add outer border to table element
- Remove duplicate borders between cells (only right/bottom on cells)
- Explicitly set border-radius on corner cells (first/last th/td)
- Add `overflow: hidden` to enforce rounded corners

Tables now have properly rounded corners matching other UI elements.
Move local workspace details from workspaces.md into new local.md page,
making it subordinate to Workspaces (matching SSH structure).

Changes:
- Create docs/local.md with local workspace details (worktrees, reviewing,
  filesystem layout)
- Simplify docs/workspaces.md to high-level overview with links to
  specific workspace types
- Update SUMMARY.md to include Local as sub-page under Workspaces

Structure now:
- Workspaces (overview)
  - Local (git worktree details)
  - SSH (remote workspace details)
  - Forking
  - Init Hooks

This provides better organization and makes it easier to find
workspace-type-specific information.
Move 'Reviewing Code' and 'Reviewing Functionality' sections from
local.md to workspaces.md since they apply to both local and SSH
workspaces.

Changes:
- Add reviewing sections to workspaces.md after 'Key Concepts'
- Remove reviewing sections from local.md (now focuses on worktree
  mechanics and filesystem layout)
- Add note in 'Reviewing Functionality' about detached HEAD being
  specific to local workspaces

This reduces duplication and puts shared concepts in the parent page
where they're easier to find.
@ammario ammario enabled auto-merge October 28, 2025 16:06
@ammario ammario changed the title 🤖 Improve documentation design and organization 🤖 docs: improve design and organization Oct 28, 2025
@ammar-agent
Copy link
Collaborator Author

CI Status Update

The integration tests are timing out at exactly 10 minutes on multiple retry attempts. This appears to be a CI infrastructure issue rather than a problem with the code changes.

Evidence:

  • ✅ All code-related checks pass: static checks, unit tests, E2E tests, builds
  • ✅ Changes are documentation-only (CSS theme + markdown reorganization)
  • ❌ Integration tests timeout at exactly 10m (suggests runner/infrastructure issue)
  • ❌ Multiple retries fail identically

Recommendation:
These documentation changes are safe to merge. The integration test timeouts are unrelated to the documentation improvements.

@ammario ammario added this pull request to the merge queue Oct 28, 2025
@github-merge-queue github-merge-queue bot removed this pull request from the merge queue due to failed status checks Oct 28, 2025
@ammario ammario merged commit 83142cf into main Oct 28, 2025
34 of 41 checks passed
@ammario ammario deleted the docs-cleanup branch October 28, 2025 17:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants